<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<link rel="Stylesheet" type="text/css" media="screen" href="Screen.css" />
	<title>STP_CreateBridge</title>
</head>
<body>
	<h3>STP_CreateBridge</h3>
	<hr />
	<h4>Declaration</h4>
	<pre>BRIDGE* STP_CreateBridge
(
    int portCount,
    int treeCount,
    const STP_CALLBACKS* callbacks,
    STP_MODE compatibilityMode,
    unsigned long debugLogBufferSize
);</pre>
	<h4>Summary</h4>
	<p>Creates an STP bridge and returns a BRIDGE* object.</p>
	<h4>Parameters</h4>
	<dl>
		<dt>portCount</dt>
		<dd>The number of ports this bridge will have. Usually equal to the number of physical ports
			present on the device.</dd>
		<dt>treeCount</dt>
		<dd>Number of MSTP spanning trees. Must be 1 in RSTP mode, and 1..64 in MSTP mode.
			<p>
				Note that the STP library currently supports a single spanning tree in MSTP mode: the CIST
				tree. So with the current version of the library this parameter must always be 1.
			</p>
			<p>
				Passing an invalid value will cause an assertion failure in the function,
				if assertion are enabled in the build options.
			</p>
		</dd>
		<dt>callbacks</dt>
		<dd>Pointer to an application-defined <a href="STP_CALLBACKS.html">STP_CALLBACKS</a>
			structure containing pointers to application-defined STP callbacks.
			<p>
				The STP library retains only a pointer to this structure, so the structure 
				address and its content
				must remain valid for the lifetime of the STP bridge.
			</p>
		</dd>
		<dt>compatibilityMode</dt>
		<dd>One of the <a href="STP_MODE.html">STP_MODE</a> values.
			<p>Note that <code>STP_MODE_802_1D_2004 </code>
				is currently not implemented, and will probably never be, because too few devices on the market 
				support it.
			</p>
		</dd>
		<dt>debugLogBufferSize</dt>
		<dd>The size of the debug log buffer this function will allocate. Must be >= 2.
			<p>The log text is generated by the STP library code and is passed to the application via the 
				<code><a href="StpCallback_DebugStrOut.html">debugStrOut</a></code> STP callback. This callback in turn usually sends this text
				to a PC via some "debug connection". For best performance, this log should be larger
				for packet-based connections such as Ethernet, and smaller for non-packet-based connections
				such as RS232.
			</p>
			<p>Passing an invalid value will cause an assertion failure in the function,
			if assertion are enabled in the build options.</p>
		</dd>
	</dl>
	<h4>Return value</h4>
	<dl>
		<dd>A pointer to a BRIDGE object. This pointer is used for uniquely identifying the bridge while
			calling various other STP functions, such as <a href="STP_DestroyBridge.html">STP_DestroyBridge</a>.
		</dd>
	</dl>
	<h4>Remarks </h4>
	<p>
		This functions allocates all the memory required for running the bridge,
		and it does so only using the STP callback <code>
		<a href="StpCallback_AllocAndZeroMemory.html">allocAndZeroMemory</a></code>. No other STP 
		functions allocate memory. This allows the application programmer to determine empirically 
		the memory requirement of the STP library for a given bridge. The memory requirement 
		depends, among other things, on the number of ports, the number of spanning trees, and the 
		debug log size. The memory requirement is constant for a compiled program if the 
		parameters to <code>STP_CreateBridge</code> are constant.</p>
	<p>
		This function sets all STP-related parameters 
		(such as ForwardDelay, HelloTime, bridge priority, port priority etc.) to their default values from the respective
		STP standard. </p>
	<p>
		When this function exits, the bridge has no knowledge of its MAC address. The application
		must call <a href="STP_OnBridgeAddressChanged.html">STP_OnBridgeAddressChanged</a> <em>after</em>
		this function returns, and <em>before</em> calling <a href="STP_StartBridge.html">STP_StartBridge</a>.
	</p>
	<p>
		This function does not start the bridge (i.e., does not begin execution of the bridge&#39;s
		state machines). The application must explicitly start the bridge by calling <a href="STP_StartBridge.html">
			STP_StartBridge</a> later.</p>
	<p>
		Before calling this function, the application must 
		instruct the hardware to stop forwarding STP-specific BPDUs between ports, and forward 
		them instead to to the processor / microcontroller running the application; the 
		application must then pass these incoming BPDUs to the STP library by calling
		<a href="STP_OnBpduReceived.html">STP_OnBpduReceived</a>. The application must also 
		instruct the hardware to tag somehow the incoming BPDUs so as to convey <em>port number 
		information </em>together with the content of the BPDU packet. This is usually realized by 
		writing to the hardware registers of the bridge IC.</p>
	<p>
		It is a good idea to reset the bridge IC before calling this function, so as to ensure 
		that the STP library finds the hardware in a well-defined state.</p>
	
</body>
</html>
